feat(packaging): add Home Assistant add-on scaffold#7560
Open
JohnMcLear wants to merge 4 commits intoether:developfrom
Open
feat(packaging): add Home Assistant add-on scaffold#7560JohnMcLear wants to merge 4 commits intoether:developfrom
JohnMcLear wants to merge 4 commits intoether:developfrom
Conversation
Scaffolds a Home Assistant add-on under packaging/home-assistant/ that
wraps the existing etherpad/etherpad:2.6.1 Docker image, enabling
one-click install from the HA Add-on Store.
- repository.yaml declares the Etherpad add-on collection.
- etherpad/config.yaml: ingress support, per-arch image reference, and
schema-validated options for title, authentication, admin password,
default pad text, DB backend, and log level. Arch list (amd64,
aarch64) matches docker.yml's upstream matrix.
- etherpad/Dockerfile: two-stage build that copies /opt/etherpad-lite
out of the upstream image (both the upstream and HA base are Alpine,
so the tree is drop-in compatible). Avoids duplicating the 200-line
upstream build.
- rootfs/etc/cont-init.d/10-etherpad.sh: reads /data/options.json via
bashio and exports env vars. Etherpad's built-in ${ENV:default}
substitution in settings.json.template picks them up directly — no
settings.json rewrite needed.
- rootfs/etc/services.d/etherpad/{run,finish}: s6-overlay v3 service
wiring for long-running Etherpad + clean exit/crash handling.
- README.md documents install steps, configuration, ingress caveats,
and the plaintext-password security note.
- CHANGELOG.md initial entry for 2.6.1.
- .github/workflows/hassio-addon.yml: lints via frenck/action-addon-linter,
multi-arch builds amd64 + aarch64 via home-assistant/builder, pushes
to GHCR on non-PR events.
Not included (follow-up): icon.png (128×128) and logo.png (250×100);
publication route — either split to ether/home-assistant-addon-etherpad
or submit to hassio-addons/repository for discovery.
Refs ether#7529
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Review Summary by QodoAdd Home Assistant add-on scaffold for Etherpad
WalkthroughsDescription• Scaffolds Home Assistant add-on wrapping upstream Etherpad Docker image • Implements configuration via HA options with ingress proxy support • Adds multi-arch CI/CD pipeline for amd64 and aarch64 builds • Includes s6-overlay service management and environment variable rendering Diagramflowchart LR
A["HA Options<br/>config.yaml"] -->|bashio reads| B["10-etherpad.sh<br/>renders env"]
B -->|exports vars| C["Etherpad<br/>settings.json"]
D["Upstream Image<br/>etherpad:2.6.1"] -->|two-stage copy| E["HA Dockerfile<br/>Alpine base"]
E -->|s6-overlay| F["run/finish<br/>service scripts"]
F -->|starts| G["Etherpad Process<br/>port 9001"]
H["hassio-addon.yml<br/>CI workflow"] -->|lints| I["frenck/action-addon-linter"]
H -->|builds| J["home-assistant/builder<br/>multi-arch"]
J -->|pushes| K["GHCR<br/>ghcr.io/ether/..."]
File Changes1. packaging/home-assistant/repository.yaml
|
Code Review by Qodo
1. Broken multiline env export
|
The hassio-addon linter rejects keys that match their default value: - boot, hassio_api, homeassistant_api, host_network, startup Remove them; all land on their documented defaults. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
…ndent Addresses Qodo review feedback on ether#7560: 1. `init: false` was suppressing s6-overlay's own PID-1 init sequence in some HA base image variants, which would prevent `/etc/cont-init.d/*` and `/etc/services.d/*` from running and leave the container without an Etherpad process. HA's default (`init: true` on most bases) plays nicely with s6-overlay — drop the explicit override and let the base image do the right thing. 2. README documented a one-click install path against `https://github.com/ether/etherpad-lite`, but HA's Add-on Store looks for `repository.yaml` at the repo root, which is not the case here (it sits under packaging/home-assistant/). Replace that install section with a prominent note that publication is a follow-up and link to the two viable destinations (dedicated repo / umbrella hassio-addons/repository). 3. Indentation: reflow cont-init and finish scripts from 4-space to 2-space to match the repo style rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
Author
|
Qodo's |
settings.json.template's own comment says dirty is for testing only, and a one-click HA install is the "not testing" case. Flip the default option, update the cont-init case statement to set DB_FILENAME for sqlite (/data/etherpad.db) as well as dirty (/data/dirty.db, still selectable). Upstream Docker image already ships the ueberdb2 sqlite driver via rusty-store-kv, so no Dockerfile change is needed. Existing add-on installs with db_type explicitly set to dirty are unaffected; only fresh installs that leave db_type at the default get the sqlite path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
Author
|
/review |
|
Persistent review updated to latest commit 32dc78c |
Comment on lines
+13
to
+18
| echo "export TITLE=$(bashio::config 'title' | jq -Rr @sh)" | ||
| echo "export REQUIRE_AUTHENTICATION=$(bashio::config 'require_authentication')" | ||
| echo "export TRUST_PROXY=$(bashio::config 'trust_proxy')" | ||
| echo "export LOGLEVEL=$(bashio::config 'log_level')" | ||
| echo "export DEFAULT_PAD_TEXT=$(bashio::config 'default_pad_text' | jq -Rr @sh)" | ||
|
|
There was a problem hiding this comment.
1. Broken multiline env export 🐞 Bug ≡ Correctness
10-etherpad.sh renders DEFAULT_PAD_TEXT using jq -Rr @sh, which is line-oriented, so the default multi-line pad text becomes multiple lines in /etc/etherpad/env and breaks when the service run script sources it. This will cause the add-on to fail to start with the default configuration.
Agent Prompt
## Issue description
`DEFAULT_PAD_TEXT` is rendered with `jq -Rr @sh` (raw, line-oriented). Because `default_pad_text` is multi-line by default, this produces multiple lines in `/etc/etherpad/env`, which is later sourced by the service run script, causing startup failures.
## Issue Context
- `default_pad_text` in the add-on config is a YAML block scalar (multi-line).
- The env file is sourced (`. /etc/etherpad/env`), so it must be valid shell syntax.
- `settings.json.docker` consumes `DEFAULT_PAD_TEXT` via `${DEFAULT_PAD_TEXT:...}`.
## Fix Focus Areas
- packaging/home-assistant/etherpad/rootfs/etc/cont-init.d/10-etherpad.sh[13-18]
## Suggested change
Render `DEFAULT_PAD_TEXT` as a single shell-escaped string for the *entire* value (including embedded newlines), for example:
- Use `jq -Rs @sh` (slurp mode) instead of `-Rr` for `default_pad_text`, or
- Avoid jq entirely and use bash’s `printf %q` when writing exports.
Ensure the generated `/etc/etherpad/env` contains exactly one valid `export DEFAULT_PAD_TEXT=...` assignment even when the value contains newlines.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scaffolds a Home Assistant add-on under
packaging/home-assistant/that wraps the existingetherpad/etherpad:2.6.1Docker image, enabling one-click install from the HA Add-on Store.Part of #7529 — this was the specific target called out in the issue ("Software like home assistant could easily run etherpad in a docker container…"). Pairs with #7558 (Snap) and #7583 (Apt).
What's included
repository.yamldeclaring the Etherpad add-on collection.etherpad/config.yamlwith ingress support, per-arch image reference, and schema-validated options fortitle, authentication, admin password, default pad text, DB backend, and log level.etherpad/Dockerfile— two-stage build that copies/opt/etherpad-liteout of the upstream image (both the upstream image and HA base are Alpine, so the tree is drop-in compatible). Avoids duplicating the 200-line upstream build.cont-init.d+services.dscripts that read HA's/data/options.jsonviabashioand export env vars. Etherpad's built-in${ENV:default}substitution (seesettings.json.templateheader) picks them up directly — nosettings.jsonrewrite needed.README.md+CHANGELOG.mdfor the Add-on Store UI..github/workflows/hassio-addon.yml—frenck/action-addon-linter+ multi-arch build viahome-assistant/builder, pushed to GHCR. Arch list (amd64, aarch64) matches the existingdocker.ymlmatrix.Default DB is sqlite, not dirty
settings.json.templatedefaults todbType: "dirty"but warns "You shouldn't use 'dirty' for anything else than testing". A one-click HA install is exactly the "not testing" case, soconfig.yamlnow shipsdb_type: sqliteand the cont-init case statement routes sqlite to/data/etherpad.db.dirtyis still a valid option for dev but no longer the default. The upstream Docker image already bundles the ueberdb2 sqlite driver viarusty-store-kv, so no Dockerfile change is needed.Not included (follow-up)
icon.png(128×128) andlogo.png(250×100) — spec noted in the README; needs brand assets.ether/home-assistant-addon-etherpadrepo and self-publish — users add the repo URL in HA.hassio-addons/repository— see their contribution guide.Recommendation: do both — (a) is under our control, (b) gets instant reach.
Risks / unknowns
trustProxy+X-Forwarded-*headers, which should work for HTTP + websockets but may have edge-case breakage. Fallback: direct port 9001 (documented in the README).ep_hash_authvia a later iteration.node:lts), the Dockerfile must switch to installing from source inside the HA base. Flagged in the Dockerfile comment.Test plan
action-addon-linterpasses in CIhome-assistant/builderproduces images for amd64 and aarch64/data/etherpad.dbexists and is non-empty)db_typetodirty, restart, confirm/data/dirty.dbis used instead (regression guard for the case statement)admin_password, log into/admin, confirm accessdb_type: postgreswith valid credentials, confirm Etherpad connectsRefs #7529
🤖 Generated with Claude Code